Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

Finding Interesting Times

The Movie Toolbox provides a set of functions that help you locate samples in movies, tracks, and media structures. These functions are based on the concept of "interesting times." An interesting time refers to a time value in a movie, track, or media that meets certain search criteria. You specify the search criteria to the Movie Toolbox. The Movie Toolbox then scans the movie, track, or media, and locates time values that meet those search criteria.

You can use these functions to search through image sequences. For example, you may want to locate each frame in an image sequence. Or you may be more interested in key frames, especially if you are trying to optimize display performance. In image data, sync samples are referred to as key frames. For more information on key frames, see the chapter "Image Compression Manager" in this book. An easy way to determine whether a movie has been edited is to look for track edits in the movie data. You may also be interested in searching for samples in a movie's media. If you set the appropriate search criteria, the Movie Toolbox locates the appropriate frames for you. You need the functions described in this section because QuickTime doesn't have a fixed rate. Each frame can have its own duration.

The Movie Toolbox identifies an interesting time by specifying its starting time and duration. The starting time indicates the time in the movie, track, or media where the search criteria are met. The duration indicates the length of time during which the search criteria remain in effect. For example, if you are looking for samples in a media, the start time would indicate the beginning of the sample, and the duration would indicate the length of time to the next sample. In this case, you could find the next media sample by adding the duration to the start time. These duration values are always positive--you determine the direction of the search by setting the sign of the rate value you supply to the functions.

Note that movie interesting times are defined in the scope of the movie as a whole. As a result, one interesting time ends when another interesting time starts in any track in the movie. For example, if you are looking for key frames in a movie, the duration value from one interesting time tells you when the next key frame starts. However, that second key frame may be in a different track in the movie. Therefore, the duration of the interesting time does not necessarily correspond to the duration of the key frame.

You can use the GetMovieNextInterestingTime function to locate times of interest in a movie. The GetTrackNextInterestingTime function lets you work with tracks. Use the GetMediaNextInterestingTime function to locate samples in a media.

GetMovieNextInterestingTime

The GetMovieNextInterestingTime function searches for times of interest in a movie. This function examines only the movie's enabled tracks.

pascal void GetMovieNextInterestingTime (Movie theMovie,
                                         short interestingTimeFlags,
                                         short numMediaTypes,
                                         const OSType *whichMediaTypes,
                                         TimeValue time, Fixed rate,
                                         TimeValue *interestingTime,
                                         TimeValue *interestingDuration);
theMovie
Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).
interestingTimeFlags
Specifies the search criteria. Note that you may set only one of the  nextTimeMediaSample , nextTimeMediaEdit , nextTimeTrackEdit and nextTimeSyncSample flags to 1. The following flags are available (set unused flags to 0):
nextTimeMediaSample
Searches for the next sample in the movie's media. Set this flag to 1 to search for the next sample.
nextTimeMediaEdit
Searches for the next group of samples in the movie's media. Set this flag to 1 to search for the next group of samples.
nextTimeTrackEdit
Searches for the media sample that corresponds to the next entry in a track's media edit list. The end of the track is considered an empty edit. Set this flag to 1 to search for the next track edit.
nextTimeSyncSample
Searches for the next sync sample in the movie's media. Set this flag to 1 to search for the next sync sample.
Sync samples do not rely on preceding frames for content. Some compression algorithms conserve space by eliminating duplication between consecutive frames in a sample.
nextTimeEdgeOK
Instructs the Movie Toolbox that you are willing to receive information about elements that begin or end at the time specified by the time parameter. Set this flag to 1 to accept this information.
This flag is especially useful at the beginning or end of a movie. The function returns valid information about the beginning and end of the movie.
nextTimeIgnoreActiveSegment
Instructs the Movie Toolbox to look outside of the active segment for samples that meet the search criteria. Set this flag to 1 to search outside of the active segment.
numMediaTypes
Specifies the number of media types in the table referred to by the whichMediaType parameter. Set this parameter to 0 to search all media types.
whichMediaTypes
Contains a pointer to an array of media types. You can use this parameter to limit the search to a specified set of media types. Each entry in the table referred to by this parameter identifies a media type to be included in the search. You use the numMediaTypes parameter to indicate the number of entries in the table. Set this parameter to nil to search all media types.
VisualMediaCharacteristic 'eyes'
Instructs the Movie Toolbox to search all tracks that have spatial bounds.
AudioMediaCharacteristic 'ears'
Instructs the Movie Toolbox to search all tracks that play sound.
time
Specifies a time value that establishes the starting point for the search. This time value must be expressed in the movie's time scale.
rate
Contains the search direction. Negative values cause the Movie Toolbox to search backward from the starting point specified in the time parameter. Other values cause a forward search.
interestingTime
Contains a pointer to a time value. The Movie Toolbox returns the first time value it finds that meets the search criteria specified in the flags parameter. This time value is in the movie's time scale.
If there are no times that meet the search criteria you specify, the Movie Toolbox sets this value to -1.
If you are not interested in this information, set this parameter to nil .
interestingDuration
Contains a pointer to a time value. The Movie Toolbox returns the duration of the interesting time. This time value is in the movie's time coordinate system. Set this parameter to nil if you do not want this information--in this case, the function works more quickly.

DESCRIPTION

You can use the GetMovieNextInterestingTime function to step through the frames of a movie one by one. If no tracks match the media types, the invalidMedia error is returned.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

invalidTrack

-2009

This track is corrupted or invalid

invalidMovie

-2010

This movie is corrupted or invalid

invalidTime

-2015

This time value is invalid

GetTrackNextInterestingTime

The GetTrackNextInterestingTime function searches for times of interest in a track.

pascal void GetTrackNextInterestingTime (Track theTrack,
                                         short interestingTimeFlags,
                                         TimeValue time, Fixed rate,
                                         TimeValue *interestingTime,
                                         TimeValue *interestingDuration);
theTrack
Specifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack (described on NewMovieTrack and GetMovieTrack , respectively).
interestingTimeFlags
Specifies the search criteria. Note that you may set only one of the  nextTimeMediaSample , nextTimeMediaEdit , nextTimeTrackEdit and nextTimeSyncSample flags to 1. The following flags are available (set unused flags to 0):
nextTimeMediaSample
Searches for the next sample in the track's media. Set this flag to 1 to search for the next sample.
nextTimeMediaEdit
Searches for the next group of samples in the track's media. Set this flag to 1 to search for the next group of samples.
nextTimeTrackEdit
Searches for the media sample that corresponds to the next entry in a track's media edit list. The end of the track is considered an empty edit. Set this flag to 1 to search for the next track edit.
nextTimeSyncSample
Searches for the next sync sample in the track's media. Set this flag to 1 to search for the next sync sample.
Sync samples do not rely on preceding frames for content. Some compression algorithms conserve space by eliminating duplication between consecutive frames in a sample.
nextTimeEdgeOK
Instructs the Movie Toolbox that you are willing to receive information about elements that begin or end at the time specified by the time parameter. Set this flag to 1 to accept this information.
This flag is especially useful at the beginning or end of a track. The function returns valid information about the beginning and end of the track.
nextTimeIgnoreActiveSegment
Instructs the Movie Toolbox to look outside of the active segment for samples that meet the search criteria. Set this flag to 1 to search outside of the active segment.
time
Specifies a time value that establishes the starting point for the search. This time value must be expressed in the movie's time scale.
rate
Contains the search direction. Negative values cause the Movie Toolbox to search backward from the starting point specified in the time parameter. Other values cause a forward search.
interestingTime
Contains a pointer to a time value. The Movie Toolbox returns the first time value it finds that meets the search criteria specified in the flags parameter. This time value is in the movie's time scale.
If there are no times that meet the search criteria you specify, the Movie Toolbox sets this value to -1.
Set this parameter to nil if you are not interested in this information.
interestingDuration
Contains a pointer to a time value. The Movie Toolbox returns the duration of the interesting time. This time value is in the movie's time coordinate system. Set this parameter to nil if you do not want this information--in this case, the function works more quickly.

ERROR CODES

invalidTrack

-2009

This track is corrupted or invalid

invalidTime

-2015

This time value is invalid

GetMediaNextInterestingTime

The GetMediaNextInterestingTime function searches for times of interest in a media.

pascal void GetMediaNextInterestingTime (Media theMedia,
                                         short interestingTimeFlags,
                                         TimeValue time, Fixed rate,
                                         TimeValue *interestingTime,
                                         TimeValue *interestingDuration);
theMedia
Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).
interestingTimeFlags
Specifies the search criteria. Note that you may set only one of the  nextTimeMediaSample , nextTimeMediaEdit and nextTimeSyncSample flags to 1. The following flags are available (set unused flags to 0):
nextTimeMediaSample
Searches for the next sample in the media. Set this flag to 1 to search for the next sample.
nextTimeMediaEdit
Searches for the next group of samples in the media. Set this flag to 1 to search for the next group of samples.
nextTimeSyncSample
Searches for the next sync sample in the media. Set this flag to 1 to search for the next sync sample.
Sync samples do not rely on preceding frames for content. Some compression algorithms conserve space by eliminating duplication between consecutive frames in a sample.
nextTimeEdgeOK
Instructs the Movie Toolbox that you are willing to receive information about elements that begin or end at the time specified by the time parameter. Set this flag to 1 to accept this information.
This flag is especially useful at the beginning or end of a media. The function returns valid information about the beginning and end of the media.
time
Specifies a time value that establishes the starting point for the search. This time value must be expressed in the media's time scale.
rate
Contains the search direction. Negative values cause the Movie Toolbox to search backward from the starting point specified in the time parameter. Other values cause a forward search.
interestingTime
Contains a pointer to a time value. The Movie Toolbox returns the first time value it finds that meets the search criteria specified in the flags parameter. This time value is in the media's time scale.
If there are no times that meet the search criteria you specify, the Movie Toolbox sets this value to -1.
Set this parameter to nil if you are not interested in this information.
interestingDuration
Contains a pointer to a time value. The Movie Toolbox returns the duration of the interesting time. This time value is in the media's time coordinate system. Set this parameter to nil if you do not want this information--in this case, the function works more quickly.

DESCRIPTION

GetMediaNextInterestingTime ignores all the edits that are defined in a movie's tracks.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

invalidTime

-2015

This time value is invalid

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next